Common

api.ledControl(state)

Overview

Turns ON or OFF the on board LED. It can be also used for debugging purposes.

Arguments

• state (integer) - sets LED state (1=ON, 0=OFF)

Example

--turns on blue LED
api.ledControl(1)

api.delayms(ms)

Overview

Pause the execution for ms milliseconds.

Arguments

• ms (integer) - The number of milliseconds to delay

Example #1

api.delayms(1000) --delay one second

Example #2

api.ledControl(1) -- turn on blue LED
api.delayms(1000) -- wait 1 second
api.ledControl(0) -- turn off blue LED

api.randInt(min, max)

Overview

Generate random number within given range.

Available only for LoRaWAN devices (function uses it's module to generate random number)

Arguments

• min (integer) - beginning number of the interval
• max (integer) - end number of the interval

Return

• number (Integer)

Example

-- generates random number within interval from 5 to 20
ran=api.randInt(5, 20)

api.getUniqueNumber()

Overview

Returns an unique integer number in range (in range from 0 to 2^32)*.

Return

• num (integer) - Unique number

Example

--get an unique number
num = api.getUniqueNumber()

api.getBatteryVoltage()

Overview

Get curent battery voltage in mV.

Return

• voltage (Integer)

Example

--get battery voltage value in mV
mv = api.getBatteryVoltage()

api.getTick(int)

Overview

Returns current number of milliseconds since startup. Counts up to 2^32 and then restarts from 0. By default it's using RTC derived tick which is incremented during sleep, but it's possible to explicitly select systick, which isn't.

Arguments

• int (integer) (optional)
  • 2 to use RTC derived tick and return value in seconds
  • 1 to use RTC derived tick and return value in ms (default)
  • 0 to use systick (value in ms)
• int (integer) (optional) (if first argument is 0)
  • 1 - reset systick value to 0
  • 0 - do not reset the systick (default)

Return

• tick (integer) - Value according to argument (in seconds / milliseconds)

Example

--get a timestamp, can be used for timing
timestamp = api.getTick()
-- to show the amount of milliseconds you can use print() function
print(timestamp)

api.dumpArray(str)

Overview

Prints contents of variable as hexadecimal string (dumps array into console)

Arguments

• str (string) - variable to print

Example

--print string "123ef" as hexadecimal
api.dumpArray("123ef")
--OUTPUT 00 : 31 32 33 65 66

api.float(op,form,arg1,arg2)

Overview

Performs operation with given floating point data.

Only if it's allowed by the firmware. Convert function available from FW version v2.5.1

Arguments

• op (string) - The operation to perform (“add” - addition, “sub” - substraction of arg2 from arg1, “mul” - multiplication, “div” - division of arg1 by arg2, “coerce” - coercion, unary operation using only arg1, “convert” - conversion of integer to float, unary operation using only arg1)

• form (string) - Two or three characters specifying the format of input/output data.

  • first position is for arg1.
  • second either specifies the format of arg2 or if last, specifies the format of return data, which are the same
  • by adding “N” to end of a string it coerces and returns little endian integer (OPTIONAL)

• arg1 (string) - The first operation argument, formated as specified in format.

• arg2 (string) - The second operation argument, formated as specified in format.

Return

• result (string, integer) - Returns result of operation, either 4 bytes little/big endian (depends on form parameter) IEEE 754 float or string float representation or integer value

Example #1

-- Multiply IEE 754 float with a floating point constant and return coerced value
-- S - string float representation, e.g. “2.234”
-- B - binary little endian IEEE 754 representation as 4 characters/bytes in a string

ret = api.float("mul", "SSN", "12.8", "1000.0")
print(ret)
-- output = 12800

ret = api.float("mul", "SSS", "12.8", "1000.0")
print(ret)
-- output = 12800.0000

Example #2

-- hexadecimal interpretation of a number 12.8 is 0x414CCCCD (IEE 754)

x=string.char(0xCD,0xCC,0x4C,0x41)
ret = api.float("mul", "BSS", x, "1000.0")
print(ret)

-- output = 12800.0000

Example #3

-- Convert integer to IEE 754 float
-- N - Input in little endian integer(for convert only)/Returns ouput as little endian integer
-- I - Binary little endian integer representation as 4 characters/bytes in a string(for convert only).
-- B - binary little endian IEEE 754 representation as 4 characters/bytes in a string
-- > - returns result as big endian, if used as output IEEE 754 representation as 4 characters/bytes in a string
-- < - returns result as little endian, if used as output IEEE 754 representation as 4 characters/bytes in a string (default value)

y=string.char(0xCD,0xCC,0x4C,0x42)
ret = api.float("convert", "IB", y)
api.dumpArray(ret)
-- output = 9A 99 84 4E

y=125
ret = api.float("convert", "NB>", y)
api.dumpArray(ret)
-- output = 42 FA 00 00

api.setVar(index, value, bool)

Overview

Saves a persistent variable value, can be used between different wake up iterations.

Arguments

1. index (integer) - Index of the variable to write, 0 to 15 is available for RAM variables (lost on reset), 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and 48 to 1071 is available for variables stored in EEPROM (100k writes).
2. value (integer) - Value to store at index
3. bool (boolean)(optional) - Optional argument, which stores bitwise negation of stored value into address higher by one

OR

2. mode (string) - explicit memory mode, currently "bytes" mode supported
3. value (string) - string array buffer to write

Example

--set persistent variable value from index 1000 to value of 3424
--can be used to send different data between wake-ups
--for variables persistent between device reset,
--use indexes 48 to 1071
api.setVar(1000, 3424)

Example (string)

myVariable = "This is some string to store to eeprom"
api.setVar(29, #myVariable) -- save the length for later readout
api.setVar(30, "bytes", myVariable) -- consumes in total ceil(#myVariable / 4) 32-bit indexes in EEPROM/RAM/HEE

api.getVar(index)

Overview

Returns persistent variable value, can be used between different wake up iterations.

Arguments

1. index (integer) - Index of the variable to read, 0 to 15 is available for RAM variables (lost on reset), 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and 48 to 1071 is available for variables stored in EEPROM (100k writes).
2. default (integer)(optional) - Default value, which is returned if value stored in the address is same as bitwise negation of value stored in address higher by one

OR

2. mode (string) - Mode to use, currently supported "bytes"
3. length (int) - Length in bytes to read

Returns

• value (integer)(string) - Value of the 32bit variable, or string.

Example

--get persistent variable value from index 1000
--can be used to send different data between wake-ups
--for variables persistent between device reset,
--use indexes 48 to 1071
slotNumber = api.getVar(1000)

Example (string)

stringLength = api.getVar(29)
myReadout = api.getVar(30, "bytes", stringLength)
print(myReadout) -- should print "myVariable" content!

api.wakeUpAt(day, hour, minute, second)

Overview

Schedules the next wake up event of the device to provided day of month (day), hour, minute and second. The provided wake up date is therefore absolute and not relative as in wakeUpIn().

Arguments

• day (integer) - Day of month, range 1 to 31
• hour (integer) - Hour, range 0 to 23
• minute (integer) - Minute, range 0 to 59
• second (integer) - Second, range 0 to 59
• resetOnFail (integer) - Reboot device when setting of wake-up event failed (1 - true, 0 or nothing - false)

Return

• status (integer) - Execution status, 0 for success and -1 for error

Example

--schedules next wake up to the 25th, 2:22:58
status = api.wakeUpAt(25, 2, 22, 58)

api.wakeUpIn(day, hour, minute, second)

Overview

Schedules the next wake up event of the device after specified time interval. The provided wake up date is therefore relative and not absolute as in wakeUpAt(). Note: The input arguments are not limited, but the total period specified must not exceed 31 days. (e.g. hour = 40, days = 2 gives a period of 3 days and 16 hours).

Arguments

• day (integer) - Day, range from 0 to 31
• hour (integer) - Hour, range 0 to X
• minute (integer) - Minute, range 0 to X
• second (integer) - Second, range 0 to X
• resetOnFail (integer) - Reboot device when setting of wake-up event failed (1 - true, 0 or nothing - false)

Return

• status (integer) - Execution status, 0 for success and -1 for error

Example

--schedules next wake up in 1 day and 122 minutes
status = api.wakeUpIn(1, 0, 122, 0)

api.getTimeDate()

Overview

Returns current date and time set on this device. The time can be synchronized over LoRa, or when uploading LUA script using LUA scripting interface.

Return

• year (integer) - Current year
• month (integer) - Current month
• day (integer) - Current day of month
• hour (integer) - Current hour
• minute (integer) - Current minute
• second (integer) - Current second

Example

--read current date and time
y,M,d,h,m,s = api.getTimeDate()

api.setTimeDate(year, month, day, hour, minute, second)

Overview

Set date and time on this device.

Arguments

• year (integer)
• month (integer)
• day (integer)
• hour (integer)
• minute (integer)
• second (integer)

Example

--set date and time
api.setTimeDate(2022, 1, 31, 23, 59, 0)

api.voltageSourceState(state, voltage)

Overview

Turn ON/OFF voltage source

Only for variants with voltage source.

The voltage option is available only for variant with adjustable option.

Arguments

• state (integer) - 1=ON, 0=OFF
• voltage (integer)(optional) - sets the voltage (mV) to the closest possible value (Available for variant with adjustable option!)

Example

--turn on voltage source
api.voltageSourceState(1)
--turn off voltage source
api.voltageSourceState(0)

api.stdin(option, opt1, opt2, opt3)

Overview

Read stdin (standard input) data or control button (get status, wait for button).

This function is using serial line, therefore use of this function in an interactive console (GUI) is not possible.

Arguments

1. "start" api.stdin("start", size) Start reading serial line.
   • size (int)(optional) = memory size (default 1024)
2. "stop" api.stdin("stop") Stop reading serial line.
3. "waitbutton" api.stdin("waitbutton", timeout) Wait for button to get pressed
   • timeout (int)(optional) = 0 by default
4. "readbutton" api.stdin("readbutton") Read status of the button.
5. "read" api.stdin("read", maxsize) Read serial line.
   • maxsize (int)(optional) = maximu size of data (default 0)
6. "readblock" api.stdin("readblock", maxsize, timeout) Read until maximum size or timeout is reached.
   • maxsize (int)(optional) = maximu size of data (default 0)
   • timeout (int)(optional) = 0 by default
7. "readuntil" api.stdin("readuntil", maxsize, stopByte, timeout) Read until maximum size, specified byte or timeout is reached.
   • maxsize (int)(optional) = maximu size of data (default 0)
   • stopByte (int)(optional) = '\n' by default
   • timeout (int)(optional) = 0 by default

Return

1. "waitbutton" res=api.stdin("waitbutton", timeout) Returns:
   • res(int) = -1 if failed or time (in ms) when pressed since this function was called.
2. "read" num, data = api.stdin("read", maxsize) Returns:
   • num (int) = received amount of Bytes
   • data (string) = received data
3. "readblock" num, data = api.stdin("readblock", maxsize, timeout) Returns:
   • num (int) = received amount of Bytes
   • data (string) = received data
4. "readbuntil" num, data = api.stdin("readuntil", maxsize, stopByte)
   • num (int) = received amount of Bytes
   • data (string) = received data

api.stdout(out, size, offset)

Overview

Write to stdout (standard output) without adding line termination. Can be useful when implementing raw serial protocols.

Arguments

• out (string) - string buffer to print to serial console (without adding newlines, raw print)
• size (int)(optional) - size of out to print (default prints entire out in other words #out)
• offset (int)(optional) - number of bytes to skip in out (default 0)

api.setVerbosity(num, opt)

Overview

Controls the amount of prints into the serial line.

Arguments

• num (integer) - sets general verbosity level

  • 0 - NONE
  • 1 - ERROR
  • 2 - WARNING
  • 3 - INFO (set by default)
  • 4 - SLOW
  • 5 - MAX

• opt (string)(optional) - specifying verbosity to specific function Here is a list of available specifiers depending on the version of the converter:

  • "LORA"
  • "LORA_HW"
  • "RADIO"
  • "LORA_TIMER"
  • "NBIOT"
  • "RTC"
  • "HWAPI_COMMON"
  • "HWAPI_DALI"
  • "HWAPI_DIO"
  • "HWAPI_DS18B20"
  • "HWAPI_LORA"
  • "HWAPI_MBUS"
  • "HWAPI_MEMORY"
  • "HWAPI_RS485"
  • "HWAPI_S0"
  • "HWAPI_SENSIRION"
  • "HWAPI_TIME"
  • "HWAPI_UART"
  • "HWAPI_WMBUS"
  • "WMBUS_HW"

To configure the timestamp, the specification of the arguments looks like this:

• num (integer) - sets verbosity level in case of "TIMESTAMP_MODE" specified

  • 0 - NONE
  • 1 - TICK
  • 2 - RTC_TICK
  • 3 - TIME
  • 4 - DATETIME

• opt (string)(optional) - specifier

  • "TIMESTAMP_MODE"

Example

--turn off timestamp
api.setVerbosity(0,"TIMESTAMP_MODE")

api.exec(command, arg1, arg2, ...)

Overview

Executes a system command or Lua fragment (additionaly uploaded Lua API extension, according to https://ieeexplore.ieee.org/document/8733437)

Arguments

• command (string)(optional) = command name or Lua API extension / fragment name

Commands:

1. "_get_wake_info"
   • returns 3 (NB-IoT: wake-up reason, serial status, NB-IoT serial status) or 2 (LoRaWAN: wake-up reason, serial status)
   • wake-up reason (string)
     • "button" - button was pressed
     • "serial" - serial interface connected
     • "timer" - RTC wake-up timer
   • serial status (string)
     • "connected" - serial line is connected
     • "disconnected" - serial line is disconnected (not detected)
   • NB-IoT serial status (string)
     • "active" - module serial output (transmit) is high - module is active
     • "inactive" - module likely sleeps, serial line is low
2. "_free_mem"
   • returns number of free heap memory in bytes
   • free heap (int) - free heap memory in bytes
3. "_sysinfo"
   • returns table with system information
   • value["SN"] - returns Serial Number of the device (-1 for old devices)
   • value["ver"] - firmware version in format 2.9.12 (major.minor.bugfix)
     • value ["ver"]["major"] - major firmware version
     • value ["ver"]["minor"] - minor firmware version
     • value ["ver"]["bugfix"] - bugfix firmware version
     • value ["ver"]["sha"] - sha reference to git repository
   • value["tim"] - build time
     • value ["tim"]["hour"] - build hour
     • value ["tim"]["min"] - build minute
     • value ["tim"]["sec"] - build second
   • value["date"] - build date
     • value ["date"]["yr"] - build year
     • value ["date"]["mon"] - build month
     • value ["date"]["day"] - build day of month
   • value["model"] - device model information
     • value ["model"]["name"] - *name of device model of ACR-CV, e.g. "ACR_CV_101N_W_D2_DEDICATED"*
     • value ["model"]["source"] - *power source name, "ac" or "battery"*
4. "_format_eeprom"
   • filler (integer)(optional)
   • erases internal device EEPROM to value 0xFF (unless second argument - filler - is defined)
   • deletes last Lua error report and all values set by api.setVar()
5. "_get_last_error"
   • report type (string) - type of report to read (default "SHORT")
     • "SHORT" - short descript of Lua error (line, and single sentence)
     • "TRACEBACK" - text traceback including global and local variables values (lzf-compressed)
     • "STDOUT" - last 1024 bytes of stdout prints before the crash (lzf-compressed)
     • "STDOUT_RAW" - as "STDOUT" but uncompressed, printable
     • "TRACEBACK_RAW" - as "TRACEBACK" but uncompressed, printable
     • "ALL" - "TRACEBACK" and "STDOUT" combined (lzf-compressed)
   • action (string) or start (int) - action to execute with given entry type
     • "len" - returns length of given type in bytes
     • "clear" - clears last error entry
     • or bytes offset (defaults to 0) since start of entry type to return
   • end (int) - end index of buffer to return, use -1 to return all
   • check LUA script for example usage
6. "_current_serial_log"
   • returns current serial log history (1024 bytes) as string
7. "_sleep"
   • seconds (int) (optional) - number of seconds to sleep (defaults to 0)
   • sleeps for provided number of seconds or if seconds is 0, sleeps without RTC timeout, use with caution!
8. "acrComTx"
   • data (string) - send payload as "acrCom" communication protocol frame, used internally with gui.acrios.com
9. "_reset" - resets the device, starting again by running bootloader
10. "_interactive_line_maxlen" - set or get max length of input for interactive mode
    • value (int) (optional) - size of input command buffer in bytes (defaults to -1)
    • in case -1 or no argument is provided, function returns currently set value (default is 2048 bytes)
    • if other value is provided, the newly allocated maximum value is returned - in case of failure, 0 is returned
11. "_cpu_temp" - get CPU temperature in degrees Celsius (+-5 deg.C)
    • returns temperature as integer
12. "_acrComHeader" - computes ACRCOM header, used for example in NWD Lua script
    • data (string) - string buffer to use to compute the header from
    • returns 7 bytes string buffer containing: [0x00][little endian data length (2 bytes)][bitwise negation of previous field (2 bytes)][CRC16-CCIT (2 bytes)]
    • CRC16 used can be computed using this python code:
13. "_print_mode" - print mode configuration
    • mode (string)
      • "ALL" - print even if no serial line is not connected (default)
      • "CONNECTED" - print only when serial line is connected
      • "NONE" - do not print
14. "clearSwWdogNoCom" - clears no-communication watchdog. If the function api.nbSend or loraSend isn't called for certain time, device resets. You can prevent this by using this function. (7 days by default)
15. "clearSwWdogNoSleep" - clear no-sleep watchdog. If device doesn't go to sleep for certain time, it resets. To prevent this from happening, you can call this function. (3 days by default)
16. "setSwWdogNoComReloadValue" - change value of no-communication watchdog. By default it's 7 days.
17. "setSwWdogNoSleepReloadValue" - change value of no-sleep watchdog. By default it's 3 days.
18. "_set_crlf_handler" - settings of CRLF handling
    • "noprint" - removes CRLF
    • "asis" - leaves CRLF as is
    • "space" - replaces CRLF with space
    • "newline" - Replaces CRLF with newline (\n)

def CB_calculateCrc16(data):
    def crc16_ccitt_update(byte, crc):
        # For each bit in the data byte, starting from the leftmost bit
        for i in range(7, -1, -1):
            # If leftmost bit of the CRC is 1, we will XOR with
            # the polynomial later
            xor_flag = (crc & 0x8000) != 0

            # Shift the CRC, and append the next bit of the
            # message to the rightmost side of the CRC
            crc = crc << 1
            if (byte & (1 << i)) != 0:
                crc = crc | 1

            # Perform the XOR with the polynomial
            if xor_flag:
                crc = crc ^ 0x1021
        return crc & 0xFFFF

    retCrc = 0xFFFF

    # last is the payload
    for i in range(len(data)):
        retCrc = crc16_ccitt_update(data[i], retCrc)

    # Augment 16 zero-bits
    for i in range(2):
        retCrc = crc16_ccitt_update(0, retCrc)
    return retCrc

19. "_has_new_reset_log" - flag showing whether asynchronous serial log was detected
    • returns flag as boolean

Return

• Varies according to command name, check command description.

Example

-- get converter model and power source

print(api.exec("_sysinfo")["model"]["name"]) --result e.g.: ACR_CV_101N_R_EAC

print(api.exec("_sysinfo")["model"]["source"]) --result e.g.: ac

api.table(command, arg1, arg2, ...)

Overview

Interface to create and manipulate memory-efficient tables and maps. Check multimode script or sendOnce script for example usage.

Arguments

• command (string) - table operation, see operations bellow
  • "set-max-id"
    • max id (integer) - maximum table index, must be >= 1
  • "get-max-id" - reads previously set value
  • "new" - creates new table
    • table id (integer) - id of newly created table, please ise set-max-id first!
    • type (string) - type of the table
      • "U32" - table is a list of integers of unsigned 32bit length
      • "I8" - table is a list of signed 8bit integers
      • "U32-I8" - table is a map/dictionary with U32 as key and I8 as value
      • "STR" - table is a list of strings
    • max length (integer) - maximum number of table entries
  • "dispose" - deletes a table
    • table id (integer) - id of an existing table
  • "insert" - inserts a new value in a table
    • table id (integer)
    • if type is "U32" or "I8":
      • value (integer) - value to insert at the end of list
    • if type is "U32-I8":
      • key (integer) - key to use in the map/dictionary
      • value (integer) - value to store at given key entry
    • if type is "STR"
      • value (string) - string to insert
  • "index-of" - returns key or index number of first occurence of given value
    • table id (integer)
    • value (integer) - value to search a key for
  • "get-index" - read value at provided index
    • table id (integer)
    • index/key (integer) - returns value at given key/index
  • "set-index" - sets value at provided index/key
    • table id (integer)
    • index/key (integer) - key or index to set the value at
    • value (integer) - value to set
  • "used" - returns number of entries in given table
    • table id (integer)
  • "clear" - clear all entries in provided table id
    • table id (integer)

Return

• Varies according to command name, check command description.

Example

Here is an example of inserting a string into the table:

--Setup table--
api.table("set-max-id", 1)
api.table("new", 1, "STR", 100)

--Inserting the value--
api.table("insert", 1, "Hello")

--Getting the value--
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [STDOUT]: Hello

--Getting index with the value--
s=api.table("index-of",1,"Hello") print(s)
--Response--
~> [STDOUT]: 1

--Getting the length of the index--
a=api.table("get-index-length",1,1) print(a)
--Response--
~> [STDOUT]: 5

--Clearing the table--
api.table("clear",1,1)
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [STDOUT]: nil

--Removing table--
api.table("dispose",1)
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [HWAPI_COMMON]: Cannot index in non-existent table ID 1
~> [STDOUT]: -1